fixes #146
fixes #121
closes #140

Hi everyone,
I've tried to get to the simplest common denominator, and incorporate some of the feedback that was already provided:

• We want the ability to use what's already in the document to update the document.
• We want single purpose actions, that are mutually exclusive, atomic, and can be combined like lego bricks.
• We want our "action keywords" to be verbs.

I'm proposing to add a copy field to the action, that's mutually exclusive with remove or update. It's functionally equivalent to the update field except that it uses a JSON path to source the JSON Node instead of defining it inline.

I know there was some additional thinking about templating expressions, sourcing from env variables etc... But I think those can be considered orthogonal and be added in a separate PR by their champions. I'd like to get the smallest possible unit that brings a meaningful contribution through.

As an image is better than a thousand words, here are a couple of examples.

Copying a node to a node that already exists

overlay: 1.1.0
info:
  title: Re-use a response for another content type
  version: 1.0.0
actions:
  - target: '$.paths["/bar"]'
    copy:  '$.paths["/foo"]'

Here the existing foo path item properties are being copied to the bar path item.

Copying a node to a node that DOES NOT already exists

overlay: 1.1.0
info:
  title: Re-use a response for another content type
  version: 1.0.0
actions:
  - target: '$.paths'
    update: { "bar": {} }
  - target: '$.paths["/bar"]'
    copy:  '$.paths["/foo"]'

Moving an item

overlay: 1.1.0
info:
  title: Re-use a response for another content type
  version: 1.0.0
actions:
   # optionally add a remove action to ensure "a clean slate" for the bar path item
  - target: '$.paths'
    update: { "bar": {} }
  - target: '$.paths["/bar"]'
    copy:  '$.paths["/foo"]'
  - target: '$.paths["/foo"]'
    remove: true

A couple of todos if that gets consensus:

• We need to stand up a v1.1-dev branch, and this needs to be rebased
• We need to add an example in the spec
• We need to update the schema
• We need to add some tests
• Editorial information (version, table, etc...) need to be applied